feat(vom): support screenshot-bound point clicks on canvas surfaces | 支持基于截图坐标点击 canvas surface - #143

问题描述

PR #138 已经能够在 observe 中发现 Canvas 可视区域，将其表示为 visual-only Surface，并允许 Agent 按 Surface ref 获取局部截图。但该 PR 只建立了“发现 Canvas → 截图”的链路。即使支持多模态的 Agent 能够从截图中识别目标，仍然无法安全地点击 Canvas 内部的具体位置。

直接使用截图坐标或视口坐标存在以下问题：

• 截图中的像素坐标不等于页面 viewport CSS 坐标。
• Canvas 可能被视口或父容器裁剪，截图只包含其当前可见区域。
• 页面可能存在设备缩放、浏览器缩放和不同 DPR。
• Canvas 可能位于 same-origin iframe、OOPIF 或嵌套 frame 中，需要进行跨 frame 坐标投影。
• 截图之后，页面可能已经发生导航、滚动、缩放、尺寸变化或重新 Observation。
• 如果截图与点击之间没有可靠绑定，Agent 可能使用过期截图点击已经变化的页面。
• Canvas 控件可能依赖 pointermove 后的异步 hit-test 更新；直接发送 press/release 不一定能触发正确行为。
• 允许 Agent 直接猜测页面坐标会绕过前序 PR 建立的视觉能力边界。

因此，需要建立一条受约束、可验证的链路，把 Agent 在某次 Surface 截图中选择的图片像素坐标，安全地转换为当前页面中的实际点击位置。

解决方案

参考 codex 的实现方法，本 PR 为 Canvas Surface 增加 screenshot-bound point click：

• Surface 截图会返回一个短期、单次使用的 Capture ID。

• Agent 将 Capture ID 和截图像素坐标传给普通 click 命令：

  bsk click @eN \
    --capture <capture-id> \
    --image-x <px> \
    --image-y <px> \
    --session <id>

• BrowserSkill 将截图坐标转换为顶层 viewport 坐标，并支持 iframe、OOPIF 和嵌套 frame。

• 点击前会校验 session、tab、Surface、页面导航、视口、滚动、缩放和 frame projection 是否仍与截图时一致。

• Capture 过期、重复使用或页面状态变化时，操作会失败，并要求重新观察和截图。

• 点击通过完整的 mouseMoved → mousePressed → mouseReleased 序列执行。

• 未提供完整 Capture 参数时，Surface ref 仍然是 screenshot-only；Agent 不能绕过截图直接猜测坐标。

边界

前序 PR 负责发现和截图 Canvas；本 PR 负责把“某次截图中的一个像素点”安全、一次性地绑定到 Canvas 点击。